

													You Can Create Your Own Mac ProgramÑ
																					With ResEdit!
	
																								By Eric Long


     It doesn't take long to become loyal to the Mac; even in the midst of groupthink, which frequently belittles Macs as computers, Òfor those not literate enough with technology to use real  computers.Ó Mac users stand by their mark and hold true to the sense that Macs are truly something special; among the throng of the ordinary.  If that is your view, your senses aren't fooling you.  There is something special indeed, and it all starts with the Mac OS.
     No doubt, if youÕre a Mac user, you know the Macintosh user interface.  You know the buttons, the menus, and the dialogs.  You probably know how great the hardware advantages are tooÑ ask your friend Joe PC about adding on new peripherals!  <snicker>.   If you've been around the block a few times with your Mac, you've probably also learned that there is a fascinating difference between the programs you use on your Mac and their PC counterparts.  What truly makes the Mac special is something called resources .
     PC files are created, basically, as a stream of bytes; one big lump of data.  Mac files can also be just a single stream of data.  Text files, GIF files, and other types of documents that can cross platforms, being usable on both Macs and PC's, are some examples of such files.  Mac applications, however, are almost universally created from resources.  MacBinary is the term created to describe this type of file format; consisting of two forks, one called the data fork, and the other the resource fork.  The data fork is the equivalent of the PC file format, a single stream of data in one big lump.  The resource fork is where Mac magic  happens.
     Anything can be placed into a resource.  Think of a resource as an organized piece of data, like a dresser drawer, organized in a preset fashion.  Resources have names, like 'MENU' for a menu resource, or 'FONT' for a font resource.  Now if you had a dresser drawer that said "SOCKS" on the front, inside you would expect to find socks.  Further, an organized person might have them placed, perhaps, according to color, then size, etc..  A resource is like an organized sock drawer.  Apple has a free utility just for organizing those sock drawersÑ called ResEdit.

GREAT, NOW HOW DO I MAKE A MAC PROGRAM?!

     The experience of creating a computer program comes at different levels.  My first computer program was created on an Apple II computer.  It looked something like this:  10 Print "Hello World";
     Not real big, but it sure impressed me.  That program was written in BASIC, a high level  programming language.  Programming languages are termed high and low according to how close they are to the level of the computer's actual machine language.  A low level language is close to the machine's language.   High level languages are designed to be closer to human language.  Today, many applications are created in large part by pointing and clicking, using programs like HyperCard and MacApp, or, using programs like ResEdit.

KIDÕS CLICKS!

     "Kid's Clicks!" is a program I wrote using ResEdit and a programming language called C.  Kid's Click's is primarily designed for kids, but not just  for kids.  By itself, the program will do little more than stare at you, although there is a cute picture of my daughter on the "About" screen you can look at!  KidÕs Clicks requires modules to come to life. 
     With your imagination and a little time, Kid's Clicks will become your  program.  Your Mac program will be a module for KidÕs Clicks!
     If you donÕt have a copy of KidÕs Clicks, you can download it from a software library online, either from your local BBS, from internet sites, or from one of the major online services.  Look for it wherever you find kidÕs games and other games.  Try out the modules included with the KidÕs Clicks program.

Note:  KidÕs Clicks requires System 7 and 256 colors.

YOU NEED RES-EDIT!

     First thing you need to create your own program is a copy of ResEdit 2.1.1 or newer.  You can download ResEdit from any major online service's forum for Mac developers, and many other places, like those mentioned before.  It is free, made publicly available by Apple.  Once you have a copy, you're ready to begin creating your program.

LET'S DO IT!

     You've got a copy of ResEdit, now you're ready to go!  Ok, here's where we start:  Kid's Clicks uses modules.  Make a copy of a Kid's Clicks module.  Remember:  Copy the module, not the KidÕs Clicks program!  Now, launch ResEdit.
      Use the Open command under the File menu to open the resource fork of your copy of the module.
     If you didn't know about ResEdit until now, this is your first look inside a Mac program!  Remember, this is a copy, so even if you screw something up, don't worry, youÕll just make another copy.  Continually saving your module as you progress will also protect you if you make a mistake.  You can always revert to the last copy saved.  If you make a mistake, first try the Undo command from the Edit menu, if that doesnÕt work, close the module without saving it, and reload the last copy saved.

												ALWAYS WORK ON A COPY, NEVER AN ORIGINAL! 

     What you should see after opening the module is a list of resources.  You can view them as a list of names, or view them as icons.  Most prefer to view the resources by their icons.  Browse around.  Double click on an icon or name of a resource type.  This will bring up a list of the resources within the module of that resource type.  Check out the 'DLOG' resources!  Peek around, see what's there!  If you start thinking, "Gee, I'd really like to know more about this stuff," you can get a great book called, ResEdit Complete , by Peter Alley and Carolyn Strange.  Ask for it at your favorite computer or book store.
     By now, you're starting to see a lot of familiar things in the module.   ResEdit means resource editor , all the resources you see can be edited with ResEdit.  That's how you're going to create your own Kid's Clicks module.

ABOUT KID'S CLICKS & MODULES

     When you create your own module, Kid's Clicks will be looking at your work to tell it what to do.  Every module contains specific information for just that purpose.  Kid's modules minimally contain the following resources, many of which you will edit to create your own:

               					1  'PICT' resource, ID# 5000
               					2  'DLOG' resources, ID#'s 1000 & 5000
               					2  'DITL' resources, ID#'s match 'DLOG' ID#'s
              					 1 - ?  'snd ' resources, ID#'s 128 - ?
              					 2  'STR ' resources, ID#'s -16396 & 5000
              					 3  'vers' resources, ID#'s 1, 2, & 128
                    

DESIGNING YOUR MODULE

     Kid's Clicks allows users to click on a picture and hear corresponding sounds played.  It's fun for kids, to hear sounds of animals, or silly sounds, and it can also be educational.  Modules can teach, entertain, inform, or just about anything.  A map with pictures of special things to click on related to each place on the map; a family photo with satirical sounds to go with the faces; a chart representing important facts, with sounds to enliven the presentation.  It's up to you, what do you want your module to do?  Have an idea in mind?  Well, let's get to work!

First, change the name of the copy you made of a Kid's Clicks module, to a name relative to your module.

You will need these items before you can begin assembling your module:

1.  Find or create a picture, a graphic that we can use in a 'PICT' resource.  You should find a picture that is fairly large, as close to 640 x 480 as possible.  KidÕs Clicks will scale your picture as needed for different screen resolutions.

2.  You need some sounds.  You can download sounds from online services and BBS's, or you can record them yourself.  You'll have to explore the options to see what's best for you.  There are many useful sound editing utilities available as freeware, shareware, and as commercial applications.  Any double-clickable sound, or any file whose type is listed as ÒSoundÓ in your windows for folders in the Finder, will work.
     These files contain resources called Ôsnd Ô resources., which we can copy and paste into your module.  Short sounds are better, because longer sounds take a lot of space to store in the module, and they take a lot of memory for KidÕs Clicks to play them.  Many sound applications will allow you to down sample  sounds to shrink the number of bytes they use.  The sound quality is reduced with down sampling, but frequently the difference isn't significantly noticable, and it may help to dramatically cut down the size of your module.
     Once youÕve collected your sounds, youÕre ready to begin completing the module.


																								   	A Typical Sound File:

Ê







LETÕS DO SOME DAMAGE!

     Use your favorite graphics program to load your picture.  Select the whole picture using "Select All" from its Edit menu (it should be there, if not you may need to determine another way to copy the picture).  Copy the picture.  Open your module in ResEdit, double-click the 'PICT' resource type, and then the ÔPICT resource whose ID# is 5000.  Paste in your new picture.  Did it work?  Great.  Now Save the module!

What can go wrong:  You donÕt want to create a new ÔPICTÕ resource.  You want to replace the picture that is currently stored in ÔPICTÕ ID# 5000 with your new picture.  If you end up with a new ÔPICTÕ, click the new one and press the DELETE key, then go back over the directions and try again.

IS THAT IT?

     Not quite, things get a little more complicated than this, but you shouldnÕt have any problem making it through the hoops.  Just take your time and carefully follow directions.

EDITING DIALOGS

     Close up the ÔPICTÕ resource type and open the ÔDITLÕ resource type.  You should find 2 ÔDITLÕ resources; one we wonÕt edit, just yet, numbered 1000, and one we will edit numbered 5000.  These resources have corresponding resources called ÔDLOGÕs.  We wonÕt need to worry about editing the ÔDLOGÕ resources until you work on an ÒAboutÓ screen for your module.

     Open ÔDITLÕ #5000.  ResEdit will bring up its ÔDITLÕ editing window.  Notice that the dialog now has your picture in it.
     The ÔDITLÕ editor lets you edit all of the items used in the dialog.  In order to tell KidÕs Clicks where a user has clicked in your dialog, we need to set up rectangular regions using an item called a Òuser itemÓ.  This dialog already contains rectangular regions used by the previous module.  Those regions will probably not be in sync with your module, so we will need to delete all of the user items used by the previous module.


Making it easy:

     Choose ÒSelect AllÓ from the Edit menu (or hit Command-A).  Every item in the ÔDITLÕ will become an active selection.  You can see that they have been actively selected by the moving outline around their rectangles.
     Hold down the SHIFT key and click in the ÔDITLÕ window in a place where there isnÕt a grayed rectangle.  (Those areas are the user items.)  Now, the picture itemÕs rectangle should not be active, the moving outline around it should be gone; while all other items are still selected.  If that isnÕt the case, go back to ÒSelect AllÓ, and try again.  If everything looks good, release the SHIFT key and hit the DELETE key.  Presto!  You have just removed every user item! YouÕre ready to begin creating your own user items.

Setting up your own user items:

     YouÕve probably noticed the floating palette next to the ÔDITLÕ editing window.  This palette contains different types of items that can be placed into a dialog.  One of them is a user item.
     Click on the palette where it says ÒUser ItemÓ and hold down the mouse button, then drag the cursor from the palette to your dialog.  This will place a new user item into the dialog.  You will add user items for each area you want to designate for users to click in to hear a different sound.  Drag the user item you just created to a place on the picture where you want to have a sound played.  In the bottom, right-hand corner of the user item is a small black box.  This box will let you re-size the user item as needed, when you click in it and drag the desired direction.
     Position and size your user item so that its rectangle encloses as much as possible the exact area you want to have a sound associated with.   When itÕs in position, double-click the user item.  In the item window that comes up, check the box labeled, ÒEnabledÓ.   Repeat this process for each area you have a sound to play.  Do not add any item types to the ÔDITLÕ other than user items.

Note:  When people use your module, the lower item number will receive mouse clicks when items overlap.

A Final Adjustment

     When youÕve added all the user items you need for each area in the dialog, select ÒSelect Item NumberÓ from the DITL menu, and select item #1.  Choose ÒSet Item NumberÓ from the same menu and change the item number to the highest number shown.
     We had to change the pictures item number, otherwise it would prevent any of your user items from receiving mouse clicks.  Save your module!

WHEW... YOU DID IT!

WIRED FOR SOUND!

     Your ready for sounds now!  This can be a tedious process, but once you get the hang of it, youÕll be on your way in a flash.
     On a piece of paper, make a list of the user items numbers in your dialog.  Next to each number write down a name for the sound you want to correspond to the location of each user item number in the dialog. If the item numbers arenÕt showing, select ÒShow Item NumbersÓ from the DITL menu. When youÕre done making your list, close up the ÔDITLÕ editor and any other associated windows that are open.

     Your sounds may be in just one file, or in several, whichever it is, begin going down your list of sounds.  Open the file containing the first sound on your list, with ResEdit.  Remember:  The sounds you are going to use must be in Ôsnd Ô resources.
     Open the Ôsnd Ô resource type in the file containing the sound you want to use.  Select the sound that you are going to use and Copy it.  If you like, you can play the sound choosing options under the snd menu whenever a Ôsnd Ô resource is highlighted.  Paste the Ôsnd Ô into your module.     Repeat this process for each sound in the file you opened; you can also use ÒSelect AllÓ to Copy and Paste all of the sounds at once.  Close the file you were copying sounds from, then proceed down your list until you have pasted all of the sounds you need into the module.

What can go wrong:  If you receive a dialog asking if youÕd like to replace resources with the same ID#, click the button that says ÒUnique IDÓ.

     When youÕve pasted into the module all of the sounds you want to use from all of the files that contained them, save your module!


Mapping It Out
      
     Now that you have all of your sounds, you can begin adjusting the ID#Õs of the Ôsnd Ô resources to correspond to the list you made of your user items.  You will highlight each Ôsnd Ô resource and use the ÒGet Resource InfoÓ command from the Resource menu to change each oneÕs ID# and to make sure each is checked ÒPurgeableÓ.

     							Here is what the window for editing resource info looks like:

Ê
















Change the ID# of each Ôsnd Ô using this method: 
          ID# = 9000 + the user item number it corresponds to.

What can go wrong:  You may run into conflicts if a Ôsnd Ô resource already exists with the ID# you need.  In that case, first find and change the other Ôsnd Ô resourceÕs ID to a number that you will not be using, or to the number it will have when youÕre done, before you change the current Ôsnd Ô resource to the number.

Check the box labeled, ÒPurgeableÓ for every ÔsndÕ resource!

When you are doneÑ save your module!


ALMOST HOME!

     If you did everything correctly, at this point you could launch your module and see your picture and have your sounds played when you click on the locations you set up.  Close your module in ResEdit and try it out!
     Did everything work?  No?!  Well, see the end of these directions for:  trouble shooting tips.

     If everything works, youÕre ready to complete your module.  Open up your module with ResEdit to finish the job.

STRINGS

     Your module contains a resource type called,  ÔSTR Ô.  This stands for ÒstringÓ.  A string to a computer is a string of characters, like letters and numbers.
       Open up the ÔSTR Ô resource type and double-click the resource whose ID# is 5000.  This is the string KidÕs Clicks will place in the Apple menu for users to select when they want to see a dialog that tells them about your module.  Change the string so that it uses the name of your module.  Save your module!

VERSION INFORMATION

     Open the ÔversÕ resource type.  You will need to edit resource ID#Õs 1 and 2, and possibly 3.  Open up the ÔversÕ resources numbered 1 and 2.  These resources are used by the Finder to display information about your module through the ÒGet InfoÓ command, and in your folder windows.  I wonÕt go into a lot of detail about doing this, but just try to adjust the strings in the ÔversÕ resources according to what you feel seems to work according to the format you see from the previous module; using appropriate information about your module.
     When youÕve done that, open up ÔversÕ resource #3.  If your module is designed to work with a version of KidÕs Clicks different than the version numbers shown, change the numbers to those that are appropriate.  Save your module!

YOUR ÒABOUTÓ SCREEN

     One last item to complete, your ÒAboutÓ screen.  Open up the ÔDITLÕ resource type and double-click on ÔDITLÕ ID#1000.  This will bring up the ÔDITLÕ resource from the former moduleÕs ÒAboutÓ screen.  Delete every item number, except item #1.  Item #1 must be a button, it should say, ÒOKÓ. 
     Now, you can design your own ÒAboutÓ screen, however you like it; except  it cannot contain any other controls, like buttons, checkboxes, radio buttons, custom controls, or editable text.  You can, however, add static text items.  Opening up those items will let you type in whatever text you want it to say.  YouÕll need to re-size the itemÕs box to fit your text. You can also add icons and pictures.  The rectangles of picture items will have to be set to fit your pictures.  You can get exact dimensions by pasting them into the Scrapbook (at least in System 7.5Õs Scrapbook), or you can use a drawing program with the capability to tell you the dimensions.
     To set up a picture on your ÒAboutÓ screen, first add another picture to your module in a ÔPICTÕ resource.  Open up the ÔPICTÕ resource type and select ÒCreate New ResourceÓ from the Resource menu; or type Command-K, to create a new ÔPICTÕ resource.  Paste your picture into the new ÔPICTÕ resource you created.  Make sure to check it as Purgeable!  When youÕre done with that, add a Picture item into the ÔDITLÕ for your ÒAboutÓ screen.  Double-click on the item to open it up.  Set the resource ID# to the ID# of the ÔPICTÕ resource you added.  To set the dimensions for the picture, I find it easiest to set the Top and Left coordinates to 0 (zero) and then enter the pictureÕs width as the Bottom coordinate, and the height as the Right coordinate, then, I just drag the picture to the right place in the ÔDITLÕ window.
     To use icons on your screen, create a ÔCICNÕ (color) icon resource and an ÔICONÕ (B&W) resource with the same ID#.  Add an Icon item to your ÔDITLÕ.  Open it and set the resource ID# to the number of your matching ÔCICNÕ and ÔICONÕ resources. 
     When youÕve finished your ÒAboutÓ screen ÔDITLÕ, save your module!

THE ÔDLOGÕ

     At this point, you will probably need to resize the dialog window to fit your ÒAboutÓ screen.  Close up the ÔDITLÕ windows you have open, and open up the ÔDLOGÕ resource type.  Select ÔDLOGÕ #1000.  ResEdit will present you with a screen that contains a window which resembles your desktop, called a miniscreen.  Inside that window is a miniaturized picture of your ÒAboutÓ screen window. 
     Pull down the Miniscreen menu and set the miniscreenÕs size to Ò512 x 342 - ClassicÓ.  Your ÒAboutÓ screen window will have to fit in the smallest resolution used by Mac monitors.  This setting will change the miniscreen to show how much space your dialog window will use on monitors with the smallest screen resolution.  If it appears to be too big to fit, you will need to do some shuffling in your ÔDITLÕ to bring it down to size.
     Since the ÔDLOGÕ and the ÔDITLÕ for your ÒAboutÓ screen have the same ID#, we can have ResEdit set the size of your dialog window to the size of your ÔDITLÕ window, for you.  Double-click on the miniature window depicting your dialog.  This will bring up the ÔDITLÕ editor again.  Now, in the lower right-hand corner of your ÔDITLÕ window is a small black square, like the user items had, to resize the window.  Size the window so that it fits your ÔDITLÕ.  If your ÔDITLÕ window is too big, edit it to bring it down to size.  When your done, close the ÔDITLÕ window and go back to the ÔDLOGÕ window.
     In the ÔDLOGÕ window, check to see that your dialog window fits on the miniscreen.  You can preview how your ÒAboutÓ screen will look like by selecting ÒPreview at Full SizeÓ from the DLOG menu.  If you need to, continue to make adjustments to your ÔDITLÕ until everything seems right.  Save your module!

FINAL CHECK

     It is important that every resource in your module have its ÒPurgeableÓ box checked.  Any resources you have added should be examined to be certain this is true.  KidÕs Clicks will run out of memory if you fail to check all the resources as purgeable.  When youÕre done, save the module, AND make a back up copy!

TROUBLE SHOOTING

     Yes, MurphyÕs Law is bound to strike you somewhere.  If youÕre having problems, check these things to see if they might be causing the problem:

     Are all of your user items Enabled?
     Are all of your resources marked Purgeable?
     Are all of the resource ID#Õs set correctly according to directions?
     Are any of your sounds an exceptionally large size in bytes?
          If so, KidÕs Clicks may not have enough memory to play them.
     Are you missing any resources from the minimum required list?
     Did you change the module fileÕs type?
          The file information for your module should have the type
          listed as ÒKmodÓ and the creator as ÒKydzÓ.
     

     Go over the directions and examine the trouble shooting tips carefully.  Hopefully, youÕll be able to work out any problems successfully and your module will be complete.  
               
YOU DID IT!!

     Congratulations!  You are now a Mac programmer!  YouÕve created a program unique to your design.   Now, call your friend Joe PC and show him how computer literate you are!

     ThereÕs much that can be done with ResEdit, alone; without hundreds of dollars of software and reference materials.  You can customize programs to your hearts content.  Be wary, however, you never really know if a change will cause a negative side effect, always work on a copy!  Save your original unmodified files.  Also, remember that while you can modify anything you own, you cannot violate someone elseÕs copyright by distributing a modified  version of their file.  KidÕs Clicks modules that you have created can be distributed, so long as items you have added do not violate copyrights themselves.  Modified versions of KidÕs Clicks itself, may not be distributed.  All of us benefit from this kind of quality control.

THE END.

ÒYou Can Create Your Own Macintosh ProgramÑ With ResEdit!Ó
By Eric Long, ©1995

This article may be reprinted with permission only.  Permission is hereby granted, up receipt of 1 copy of publication containing reprint.

Correspondence:  Email:  EricMLong@aol.com
                               CompuServe - 72764,1072
                               Postal:  4020 Jeffrey Avenue
                                           Sacramento, CA  95820-2551

ÒKidÕs Clicks!Ó ©1995 Eric Long
ResEditª © Apple Computer Inc.

Legal Disclaimer:

Neither ResEdit, nor KidÕs Clicks, or its modules, can ever be guaranteed to work without fault.  Problems can and do occur, use solely at your own risk.
